buffer 缓冲区

您所在的位置：网站首页 › buffer from › buffer 缓冲区

buffer 缓冲区

#buffer 缓冲区 | 来源: 网络整理| 查看: 265

buffer 缓冲区#

中英对照

稳定性: 2 - 稳定

源代码: lib/buffer.js

Buffer 对象用于表示固定长度的字节序列。许多 Node.js API 都支持 Buffer。

Buffer 类是 JavaScript Uint8Array 类的子类，并使用涵盖额外用例的方法对其进行扩展。 Node.js API 在支持 Buffer 的地方也接受普通的 Uint8Array。

虽然 Buffer 类在全局作用域内可用，但仍然建议通过 import 或 require 语句显式地引用它。

import { Buffer } from 'node:buffer'; // 创建长度为 10 的以零填充的缓冲区。 const buf1 = Buffer.alloc(10); // 创建长度为 10 的缓冲区， // 使用值为 `1` 的字节填充。 const buf2 = Buffer.alloc(10, 1); // 创建长度为 10 的未初始化的缓冲区。 // 这比调用 Buffer.alloc() 快， // 但返回的缓冲区实例可能包含旧数据， // 需要使用 fill()、write() 、 // 或其他填充缓冲区内容的函数重写。 const buf3 = Buffer.allocUnsafe(10); // 创建包含字节 [1, 2, 3] 的缓冲区。 const buf4 = Buffer.from([1, 2, 3]); // 创建包含字节 [1, 1, 1, 1] 的缓冲区， // 所有条目都使用 `(value & 255)` 截断以符合范围 0–255。 const buf5 = Buffer.from([257, 257.5, -255, '1']); // 创建包含字符串 'tést' 的 UTF-8 编码字节的缓冲区： // [0x74, 0xc3, 0xa9, 0x73, 0x74]（十六进制） // [116, 195, 169, 115, 116]（十进制） const buf6 = Buffer.from('tést'); // 创建包含 Latin-1 字节 [0x74, 0xe9, 0x73, 0x74] 的缓冲区。 const buf7 = Buffer.from('tést', 'latin1');const { Buffer } = require('node:buffer'); // 创建长度为 10 的以零填充的缓冲区。 const buf1 = Buffer.alloc(10); // 创建长度为 10 的缓冲区， // 使用值为 `1` 的字节填充。 const buf2 = Buffer.alloc(10, 1); // 创建长度为 10 的未初始化的缓冲区。 // 这比调用 Buffer.alloc() 快， // 但返回的缓冲区实例可能包含旧数据， // 需要使用 fill()、write() 、 // 或其他填充缓冲区内容的函数重写。 const buf3 = Buffer.allocUnsafe(10); // 创建包含字节 [1, 2, 3] 的缓冲区。 const buf4 = Buffer.from([1, 2, 3]); // 创建包含字节 [1, 1, 1, 1] 的缓冲区， // 所有条目都使用 `(value & 255)` 截断以符合范围 0–255。 const buf5 = Buffer.from([257, 257.5, -255, '1']); // 创建包含字符串 'tést' 的 UTF-8 编码字节的缓冲区： // [0x74, 0xc3, 0xa9, 0x73, 0x74]（十六进制） // [116, 195, 169, 115, 116]（十进制） const buf6 = Buffer.from('tést'); // 创建包含 Latin-1 字节 [0x74, 0xe9, 0x73, 0x74] 的缓冲区。 const buf7 = Buffer.from('tést', 'latin1'); 缓冲区与字符编码#

中英对照

版本历史版本变更 v15.7.0

引入 base64url 编码。

v6.4.0

引入 latin1 作为 binary 的别名。

v5.0.0

删除已弃用的 raw 和 raws 编码。

当在 Buffer 和字符串之间进行转换时，可以指定字符编码。如果未指定字符编码，则默认使用 UTF-8。

import { Buffer } from 'node:buffer'; const buf = Buffer.from('hello world', 'utf8'); console.log(buf.toString('hex')); // 打印: 68656c6c6f20776f726c64 console.log(buf.toString('base64')); // 打印: aGVsbG8gd29ybGQ= console.log(Buffer.from('fhqwhgads', 'utf8')); // 打印: console.log(Buffer.from('fhqwhgads', 'utf16le')); // 打印: const { Buffer } = require('node:buffer'); const buf = Buffer.from('hello world', 'utf8'); console.log(buf.toString('hex')); // 打印: 68656c6c6f20776f726c64 console.log(buf.toString('base64')); // 打印: aGVsbG8gd29ybGQ= console.log(Buffer.from('fhqwhgads', 'utf8')); // 打印: console.log(Buffer.from('fhqwhgads', 'utf16le')); // 打印:

Node.js 缓冲区接受它们接收到的编码字符串的所有大小写变体。例如，UTF-8 可以指定为 'utf8'、'UTF8' 或 'uTf8'。

Node.js 目前支持的字符编码如下：

'utf8'（别名：'utf-8'）：多字节编码的 Unicode 字符。许多网页和其他文档格式使用 UTF-8。这是默认的字符编码。当将 Buffer 解码为不完全包含有效 UTF-8 数据的字符串时，则 Unicode 替换字符 U+FFFD � 将用于表示这些错误。

'utf16le'（别名：'utf-16le'）：多字节编码的 Unicode 字符。与 'utf8' 不同，字符串中的每个字符都将使用 2 或 4 个字节进行编码。 Node.js 仅支持 UTF-16 的小端序变体。

'latin1': Latin-1 代表 ISO-8859-1。此字符编码仅支持 U+0000 至 U+00FF 的 Unicode 字符。每个字符都使用单个字节进行编码。不符合该范围的字符将被截断并映射到该范围内的字符。

使用以上编码之一将 Buffer 转换为字符串称为解码，将字符串转换为 Buffer 称为编码。

Node.js 还支持以下二进制转文本的编码。对于二进制转文本的编码，命名约定是相反的：将 Buffer 转换为字符串通常称为编码，将字符串转换为 Buffer 通常称为解码。

'base64': Base64 编码。当从字符串创建 Buffer 时，此编码还将正确接受 RFC 4648，第 5 节中指定的 "URL 和文件名安全字母表"。 base64 编码的字符串中包含的空白字符（例如空格、制表符和换行符）会被忽略。

'base64url': base64url 编码如 RFC 4648 第 5 节中指定。当从字符串创建 Buffer 时，此编码也将正确接受常规的 base64 编码的字符串。当将 Buffer 编码为字符串时，此编码将忽略填充。

'hex': 将每个字节编码为两个十六进制字符。当解码不完全由偶数个十六进制字符组成的字符串时，可能会发生数据截断。请参阅下面的示例。

还支持以下旧版字符编码：

'ascii': 仅适用于 7 位 ASCII 数据。当将字符串编码为 Buffer 时，这等效于使用 'latin1'。当将 Buffer 解码为字符串时，使用此编码将在解码为 'latin1' 之前额外取消设置每个字节的最高位。通常，没有理由使用此编码，因为在编码或解码纯 ASCII 文本时，'utf8'（或者，如果已知数据始终是纯 ASCII，则为 'latin1'）将是更好的选择。它仅用于旧版兼容性。

'binary': 'latin1' 的别名。有关此主题的更多背景信息，请参阅二进制字符串。此编码的名称很容易让人误解，因为这里列出的所有编码都在字符串和二进制数据之间进行转换。对于字符串和 Buffer 之间的转换，通常 'utf8' 是正确的选择。

'ucs2', 'ucs-2': 'utf16le' 的别名。 UCS-2 过去指的是 UTF-16 的一种变体，它不支持代码点大于 U+FFFF 的字符。在 Node.js 中，始终支持这些代码点。

import { Buffer } from 'node:buffer'; Buffer.from('1ag123', 'hex'); // 打印，当遇到第一个非十六进制值 ('g') 时，则截断数据。 Buffer.from('1a7', 'hex'); // 打印，当数据以一位数 ('7') 结尾时，则截断数据。 Buffer.from('1634', 'hex'); // 打印，表现所有数据。const { Buffer } = require('node:buffer'); Buffer.from('1ag123', 'hex'); // 打印，当遇到第一个非十六进制值 ('g') 时，则截断数据。 Buffer.from('1a7', 'hex'); // 打印，当数据以一位数 ('7') 结尾时，则截断数据。 Buffer.from('1634', 'hex'); // 打印，表现所有数据。

现代 Web 浏览器遵循 WHATWG 编码标准，其将 'latin1' 和 'ISO-8859-1' 别名为 'win-1252'。这意味着在执行 http.get() 之类的操作时，如果返回的字符集是 WHATWG 规范中列出的字符集之一，则服务器实际上可能返回 'win-1252' 编码的数据，使用 'latin1' 编码可能会错误地解码字符。

缓冲区与 TypedArray#

中英对照

版本历史版本变更 v3.0.0

类 Buffer 现在继承自 Uint8Array。

Buffer 实例也是 JavaScript Uint8Array 和 TypedArray 实例。所有 TypedArray 方法都可在 Buffer 上使用。但是，Buffer API 和 TypedArray API 之间存在细微的不兼容。

特别是：

TypedArray.prototype.slice() 创建 TypedArray 部分的副本，而 Buffer.prototype.slice() 在现有 Buffer 上创建视图而不进行复制。这种行为可能会有意外，并且仅存在于旧版兼容性中。 TypedArray.prototype.subarray() 可用于在 Buffer 和其他 TypedArray 上实现 Buffer.prototype.slice() 的行为，且应该是首选。 buf.toString() 与其对应的 TypedArray 不兼容。多种方法，例如 buf.indexOf()，支持额外的参数。

有两种方式可以从 Buffer 创建新的 TypedArray 实例：

将 Buffer 传给 TypedArray 构造函数将复制 Buffer 的内容，解释为整数数组，而不是目标类型的字节序列。 import { Buffer } from 'node:buffer'; const buf = Buffer.from([1, 2, 3, 4]); const uint32array = new Uint32Array(buf); console.log(uint32array); // 打印: Uint32Array(4) [ 1, 2, 3, 4 ]const { Buffer } = require('node:buffer'); const buf = Buffer.from([1, 2, 3, 4]); const uint32array = new Uint32Array(buf); console.log(uint32array); // 打印: Uint32Array(4) [ 1, 2, 3, 4 ] 传入 ArrayBuffer 底层的 Buffer 将创建与 Buffer 共享其内存的 TypedArray。 import { Buffer } from 'node:buffer'; const buf = Buffer.from('hello', 'utf16le'); const uint16array = new Uint16Array( buf.buffer, buf.byteOffset, buf.length / Uint16Array.BYTES_PER_ELEMENT); console.log(uint16array); // 打印: Uint16Array(5) [ 104, 101, 108, 108, 111 ]const { Buffer } = require('node:buffer'); const buf = Buffer.from('hello', 'utf16le'); const uint16array = new Uint16Array( buf.buffer, buf.byteOffset, buf.length / Uint16Array.BYTES_PER_ELEMENT); console.log(uint16array); // 打印: Uint16Array(5) [ 104, 101, 108, 108, 111 ]

通过以相同的方式使用 TypedArray 对象的 .buffer 属性，可以创建与 TypedArray 实例共享相同分配内存的新 Buffer。 Buffer.from() 在这种情况下表现得像 new Uint8Array()。

import { Buffer } from 'node:buffer'; const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; // 复制 `arr` 的内容。 const buf1 = Buffer.from(arr); // 与 `arr` 共享内存。 const buf2 = Buffer.from(arr.buffer); console.log(buf1); // 打印: console.log(buf2); // 打印: arr[1] = 6000; console.log(buf1); // 打印: console.log(buf2); // 打印: const { Buffer } = require('node:buffer'); const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; // 复制 `arr` 的内容。 const buf1 = Buffer.from(arr); // 与 `arr` 共享内存。 const buf2 = Buffer.from(arr.buffer); console.log(buf1); // 打印: console.log(buf2); // 打印: arr[1] = 6000; console.log(buf1); // 打印: console.log(buf2); // 打印:

使用 TypedArray 的 .buffer 创建 Buffer 时，可以通过传入 byteOffset 和 length 参数仅使用底层 ArrayBuffer 的一部分。

import { Buffer } from 'node:buffer'; const arr = new Uint16Array(20); const buf = Buffer.from(arr.buffer, 0, 16); console.log(buf.length); // 打印: 16const { Buffer } = require('node:buffer'); const arr = new Uint16Array(20); const buf = Buffer.from(arr.buffer, 0, 16); console.log(buf.length); // 打印: 16

Buffer.from() 和 TypedArray.from() 具有不同的签名和实现。具体来说，TypedArray 变体接受第二个参数，该参数是在类型化数组的每个元素上调用的映射函数：

TypedArray.from(source[, mapFn[, thisArg]])

但是，Buffer.from() 方法不支持使用映射函数：

Buffer.from(array) Buffer.from(buffer) Buffer.from(arrayBuffer[, byteOffset[, length]]) Buffer.from(string[, encoding]) 缓冲区与迭代器#

中英对照

可以使用 for..of 语法迭代 Buffer 实例：

import { Buffer } from 'node:buffer'; const buf = Buffer.from([1, 2, 3]); for (const b of buf) { console.log(b); } // 打印: // 1 // 2 // 3const { Buffer } = require('node:buffer'); const buf = Buffer.from([1, 2, 3]); for (const b of buf) { console.log(b); } // 打印: // 1 // 2 // 3

此外，buf.values()、buf.keys() 和 buf.entries() 方法可用于创建迭代器。

Blob 类#

中英对照

版本历史版本变更 v16.17.0

不再是实验的。

v15.7.0, v14.18.0

新增于: v15.7.0, v14.18.0

Blob 封装了不可变的原始数据，可以在多个工作线程之间安全地共享。

new buffer.Blob([sources[, options]])#

中英对照

版本历史版本变更 v16.7.0

添加了标准的 endings 选项来替换行尾，并且删除了非标准的 encoding 选项。

v15.7.0

新增于: v15.7.0

sources | | | | 将存储在 Blob 中的字符串数组、、、或对象、或此类对象的任何组合。 options endings 'transparent' 或 'native' 之一。当设置为 'native' 时，字符串源部分中的行尾将转换为 require('node:os').EOL 指定的平台原生的行尾。 type Blob 内容类型。目的是让 type 传达数据的 MIME 媒体类型，但不执行类型格式的验证。

创建新的 Blob 对象，其中包含给定源的串接。

、、和源被复制到 'Blob' 中，因此可以在创建 'Blob' 后安全地修改。

字符串源被编码为 UTF-8 字节序列并复制到 Blob 中。每个字符串部分中不匹配的代理对将被 Unicode U+FFFD 替换字符替换。

blob.arrayBuffer()#

中英对照

新增于: v15.7.0 返回:

返回使用包含 Blob 数据副本的履行的 promise。

blob.size#

中英对照

新增于: v15.7.0

Blob 的总大小（以字节为单位）。

blob.slice([start[, end[, type]]])#

中英对照

新增于: v15.7.0 start 起始索引。 end 结束索引。 type 新 Blob 的内容类型

创建并返回包含此 Blob 对象数据子集的新 Blob。原 Blob 没有改动。

blob.stream()#

中英对照

新增于: v16.7.0 返回:

返回允许读取 Blob 内容的新 ReadableStream。

blob.text()#

中英对照

新增于: v15.7.0 返回:

返回使用解码为 UTF-8 字符串的 Blob 的内容履行的 promise。

blob.type#

中英对照

新增于: v15.7.0 类型:

Blob 的内容类型。

Blob 对象和 MessageChannel#

中英对照

一旦创建了对象，就可以通过 MessagePort 将其发送到多个目的地，而无需传输或立即复制数据。只有在调用 arrayBuffer() 或 text() 方法时才会复制 Blob 包含的数据。

import { Blob, Buffer } from 'node:buffer'; import { setTimeout as delay } from 'node:timers/promises'; const blob = new Blob(['hello there']); const mc1 = new MessageChannel(); const mc2 = new MessageChannel(); mc1.port1.onmessage = async ({ data }) => { console.log(await data.arrayBuffer()); mc1.port1.close(); }; mc2.port1.onmessage = async ({ data }) => { await delay(1000); console.log(await data.arrayBuffer()); mc2.port1.close(); }; mc1.port2.postMessage(blob); mc2.port2.postMessage(blob); // 发布后 Blob 仍然可用。 blob.text().then(console.log);const { Blob, Buffer } = require('node:buffer'); const { setTimeout: delay } = require('node:timers/promises'); const blob = new Blob(['hello there']); const mc1 = new MessageChannel(); const mc2 = new MessageChannel(); mc1.port1.onmessage = async ({ data }) => { console.log(await data.arrayBuffer()); mc1.port1.close(); }; mc2.port1.onmessage = async ({ data }) => { await delay(1000); console.log(await data.arrayBuffer()); mc2.port1.close(); }; mc1.port2.postMessage(blob); mc2.port2.postMessage(blob); // 发布后 Blob 仍然可用。 blob.text().then(console.log); Buffer 类#

中英对照

Buffer 类是直接处理二进制数据的全局类型。它可以使用多种方式构建。

Buffer.alloc(size[, fill[, encoding]])#

中英对照

版本历史版本变更 v15.0.0

对于无效的输入参数，抛出 ERR_INVALID_ARG_VALUE 而不是 ERR_INVALID_OPT_VALUE。

v10.0.0

尝试使用零长度缓冲区填充非零长度缓冲区，则会触发抛出异常。

v10.0.0

为 fill 指定无效字符串，则会触发抛出异常。

v8.9.3

为 fill 指定无效字符串，现在会导致缓冲区以零填充。

v5.10.0

新增于: v5.10.0

size 新的 Buffer 所需的长度。 fill | | | 用于预填充新 Buffer 的值。默认值: 0。 encoding 如果 fill 是字符串，则这就是它的编码。默认值: 'utf8'。

分配 size 个字节的新 Buffer。如果 fill 为 undefined，则 Buffer 将以零填充。

import { Buffer } from 'node:buffer'; const buf = Buffer.alloc(5); console.log(buf); // 打印: const { Buffer } = require('node:buffer'); const buf = Buffer.alloc(5); console.log(buf); // 打印:

如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0，则抛出 ERR_INVALID_ARG_VALUE。

如果指定了 fill，则分配的 Buffer 将通过调用 buf.fill(fill) 进行初始化。

import { Buffer } from 'node:buffer'; const buf = Buffer.alloc(5, 'a'); console.log(buf); // 打印: const { Buffer } = require('node:buffer'); const buf = Buffer.alloc(5, 'a'); console.log(buf); // 打印:

如果同时指定了 fill 和 encoding，则分配的 Buffer 将通过调用 buf.fill(fill, encoding) 进行初始化。

import { Buffer } from 'node:buffer'; const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64'); console.log(buf); // 打印: const { Buffer } = require('node:buffer'); const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64'); console.log(buf); // 打印:

调用 Buffer.alloc() 可能比替代的 Buffer.allocUnsafe() 慢得多，但可确保新创建的 Buffer 实例的内容永远不会包含来自先前分配的敏感数据，包括可能尚未分配给 Buffer 的数据。

如果 size 不是数值，则会抛出 TypeError。

Buffer.allocUnsafe(size)#

中英对照

版本历史版本变更 v15.0.0

对于无效的输入参数，抛出 ERR_INVALID_ARG_VALUE 而不是 ERR_INVALID_OPT_VALUE。

v7.0.0

传入负的 size 现在会抛出错误。

v5.10.0

新增于: v5.10.0

size 新的 Buffer 所需的长度。

分配 size 个字节的新 Buffer。如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0，则抛出 ERR_INVALID_ARG_VALUE。

以这种方式创建的 Buffer 实例的底层内存不会被初始化。新创建的 Buffer 的内容是未知的，可能包含敏感的数据。使用 Buffer.alloc() 来用零初始化 Buffer 实例。

import { Buffer } from 'node:buffer'; const buf = Buffer.allocUnsafe(10); console.log(buf); // 打印（内容可能会有所不同）: buf.fill(0); console.log(buf); // 打印: const { Buffer } = require('node:buffer'); const buf = Buffer.allocUnsafe(10); console.log(buf); // 打印（内容可能会有所不同）: buf.fill(0); console.log(buf); // 打印:

如果 size 不是数值，则会抛出 TypeError。

Buffer 模块预先分配了大小为 Buffer.poolSize 的内部 Buffer 实例作为池，用于快速分配使用 Buffer.allocUnsafe()、Buffer.from(array)、Buffer.concat() 创建的新 Buffer 实例，仅当 size 小于或等于 Buffer.poolSize >> 1（Buffer.poolSize 除以二再向下取整）时才使用弃用的 new Buffer(size) 构造函数。

使用此预先分配的内部内存池是调用 Buffer.alloc(size, fill) 与调用 Buffer.alloc(size, fill) 之间的关键区别。具体来说，Buffer.alloc(size, fill) 永远不会使用内部的 Buffer 池，而 Buffer.allocUnsafe(size).fill(fill) 会在 size 小于或等于 Buffer.poolSize 的一半时使用内部的 Buffer 池。当应用程序需要 Buffer.allocUnsafe() 提供的额外性能时，差异很细微，但可能很重要。

Buffer.allocUnsafeSlow(size)#

中英对照

版本历史版本变更 v15.0.0

对于无效的输入参数，抛出 ERR_INVALID_ARG_VALUE 而不是 ERR_INVALID_OPT_VALUE。

v5.12.0

新增于: v5.12.0

size 新的 Buffer 所需的长度。

分配 size 个字节的新 Buffer。如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0，则抛出 ERR_INVALID_ARG_VALUE。如果 size 为 0，则创建零长度 Buffer。

以这种方式创建的 Buffer 实例的底层内存不会被初始化。新创建的 Buffer 的内容是未知的，可能包含敏感的数据。使用 buf.fill(0) 用零初始化此类 Buffer 实例。

当使用 Buffer.allocUnsafe() 分配新的 Buffer 实例时，4 KiB 以下的分配是从单个预分配的 Buffer 中分割出来的。这允许应用程序避免创建许多单独分配的 Buffer 实例的垃圾收集开销。这种方法无需跟踪和清理尽可能多的单个 ArrayBuffer 对象，从而提高了性能和内存使用率。

但是，在开发人员可能需要在不确定的时间内从池中保留一小块内存的情况下，使用 Buffer.allocUnsafeSlow() 创建未池化的 Buffer 实例然后复制出相关位可能是合适的。

import { Buffer } from 'node:buffer'; // 需要保留一些小块内存。 const store = []; socket.on('readable', () => { let data; while (null !== (data = readable.read())) { // 为保留的数据分配。 const sb = Buffer.allocUnsafeSlow(10); // 将数据复制到新分配中。 data.copy(sb, 0, 0, 10); store.push(sb); } });const { Buffer } = require('node:buffer'); // 需要保留一些小块内存。 const store = []; socket.on('readable', () => { let data; while (null !== (data = readable.read())) { // 为保留的数据分配。 const sb = Buffer.allocUnsafeSlow(10); // 将数据复制到新分配中。 data.copy(sb, 0, 0, 10); store.push(sb); } });

如果 size 不是数值，则会抛出 TypeError。

Buffer.byteLength(string[, encoding])#

中英对照

版本历史版本变更 v7.0.0

传入无效输入现在将抛出错误。

v5.10.0

参数 string 现在可以是任何 TypedArray、DataView 或 ArrayBuffer。

v0.1.90

新增于: v0.1.90

使用 encoding 编码时返回字符串的字节长度。这与 String.prototype.length 不同，String.prototype.length 不考虑用于将字符串转换为字节的编码。

对于 'base64'、'base64url' 和 'hex'，此函数假定输入有效。对于包含非 base64/hex 编码数据（例如空格）的字符串，返回值可能大于从字符串创建的 Buffer 的长度。

import { Buffer } from 'node:buffer'; const str = '\u00bd + \u00bc = \u00be'; console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`); // 打印: ½ + ¼ = ¾: 9 characters, 12 bytesconst { Buffer } = require('node:buffer'); const str = '\u00bd + \u00bc = \u00be'; console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`); // 打印: ½ + ¼ = ¾: 9 characters, 12 bytes

当 string 为 Buffer/DataView/TypedArray/ArrayBuffer/SharedArrayBuffer 时，返回 .byteLength 报告的字节长度。

Buffer.compare(buf1, buf2)#

中英对照

版本历史版本变更 v8.0.0

参数现在可以是 Uint8Array。

v0.11.13

新增于: v0.11.13

buf1 | buf2 | 返回: -1、0 或 1，取决于比较的结果。详见 buf.compare()。

比较 buf1 和 buf2，通常用于对 Buffer 实例的数组进行排序。这相当于调用 buf1.compare(buf2)。

import { Buffer } from 'node:buffer'; const buf1 = Buffer.from('1234'); const buf2 = Buffer.from('0123'); const arr = [buf1, buf2]; console.log(arr.sort(Buffer.compare)); // 打印: [ , ] // （此结果相当于：[buf2, buf1]。）const { Buffer } = require('node:buffer'); const buf1 = Buffer.from('1234'); const buf2 = Buffer.from('0123'); const arr = [buf1, buf2]; console.log(arr.sort(Buffer.compare)); // 打印: [ , ] // （此结果相当于：[buf2, buf1]。） Buffer.concat(list[, totalLength])#

中英对照

版本历史版本变更 v8.0.0

list 的元素现在可以是 Uint8Array。

v0.7.11

新增于: v0.7.11

list | 要连接的 Buffer 或 Uint8Array 实例的列表。 totalLength 连接时 list 中 Buffer 实例的总长度。返回:

返回新的 Buffer，它是将 list 中的所有 Buffer 实例连接在一起的结果。

如果列表没有条目，或者 totalLength 为 0，则返回新的零长度 Buffer。

如果未提供 totalLength，则从 list 中的 Buffer 实例通过相加其长度来计算。

如果提供了 totalLength，则将其强制为无符号整数。如果 list 中 Buffer 的组合长度超过 totalLength，则结果截断为 totalLength。

import { Buffer } from 'node:buffer'; // 从三个 `Buffer` 实例的列表创建单个 `Buffer`。 const buf1 = Buffer.alloc(10); const buf2 = Buffer.alloc(14); const buf3 = Buffer.alloc(18); const totalLength = buf1.length + buf2.length + buf3.length; console.log(totalLength); // 打印: 42 const bufA = Buffer.concat([buf1, buf2, buf3], totalLength); console.log(bufA); // 打印: console.log(bufA.length); // 打印: 42const { Buffer } = require('node:buffer'); // 从三个 `Buffer` 实例的列表创建单个 `Buffer`。 const buf1 = Buffer.alloc(10); const buf2 = Buffer.alloc(14); const buf3 = Buffer.alloc(18); const totalLength = buf1.length + buf2.length + buf3.length; console.log(totalLength); // 打印: 42 const bufA = Buffer.concat([buf1, buf2, buf3], totalLength); console.log(bufA); // 打印: console.log(bufA.length); // 打印: 42

Buffer.concat() 也像 Buffer.allocUnsafe() 一样使用内部 Buffer 池。

Buffer.from(array)#

中英对照

新增于: v5.10.0 array

使用 0 – 255 范围内的字节 array 分配新的 Buffer。该范围之外的数组条目将被截断以符合它。

import { Buffer } from 'node:buffer'; // 创建包含字符串 'buffer' 的 UTF-8 字节的新缓冲区。 const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);const { Buffer } = require('node:buffer'); // 创建包含字符串 'buffer' 的 UTF-8 字节的新缓冲区。 const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);

如果 array 不是 Array 或其他适用于 Buffer.from() 变体的类型，则将抛出 TypeError。

Buffer.from(array) 和 Buffer.from(string) 也像 Buffer.allocUnsafe() 一样使用内部 Buffer 池。

Buffer.from(arrayBuffer[, byteOffset[, length]])#

中英对照

新增于: v5.10.0 arrayBuffer | ArrayBuffer、SharedArrayBuffer，例如 TypedArray 的 .buffer 属性。 byteOffset 要暴露的第一个字节的索引。默认值: 0。 length 要暴露的字节数。默认值: arrayBuffer.byteLength - byteOffset。

这将创建 ArrayBuffer 的视图，而无需复制底层内存。例如，当传入对 TypedArray 实例的 .buffer 属性的引用时，新创建的 Buffer 将与 TypedArray 的底层 ArrayBuffer 共享相同的分配内存。

import { Buffer } from 'node:buffer'; const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; // 与 `arr` 共享内存。 const buf = Buffer.from(arr.buffer); console.log(buf); // 打印: // 更改原始的 Uint16Array 也会更改缓冲区。 arr[1] = 6000; console.log(buf); // 打印: const { Buffer } = require('node:buffer'); const arr = new Uint16Array(2); arr[0] = 5000; arr[1] = 4000; // 与 `arr` 共享内存。 const buf = Buffer.from(arr.buffer); console.log(buf); // 打印: // 更改原始的 Uint16Array 也会更改缓冲区。 arr[1] = 6000; console.log(buf); // 打印:

可选的 byteOffset 和 length 参数指定了 arrayBuffer 中将由 Buffer 共享的内存范围。

import { Buffer } from 'node:buffer'; const ab = new ArrayBuffer(10); const buf = Buffer.from(ab, 0, 2); console.log(buf.length); // 打印: 2const { Buffer } = require('node:buffer'); const ab = new ArrayBuffer(10); const buf = Buffer.from(ab, 0, 2); console.log(buf.length); // 打印: 2

如果 arrayBuffer 不是 ArrayBuffer 或 SharedArrayBuffer 或其他适用于 Buffer.from() 变体的类型，则将抛出 TypeError。

记住，支持 ArrayBuffer 可以覆盖超出 TypedArray 视图边界的内存范围。使用 TypedArray 的 buffer 属性创建的新 Buffer 可能会超出 TypedArray 的范围：

import { Buffer } from 'node:buffer'; const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 个元素 const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 个元素 console.log(arrA.buffer === arrB.buffer); // true const buf = Buffer.from(arrB.buffer); console.log(buf); // 打印: const { Buffer } = require('node:buffer'); const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 个元素 const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 个元素 console.log(arrA.buffer === arrB.buffer); // true const buf = Buffer.from(arrB.buffer); console.log(buf); // 打印: Buffer.from(buffer)#

中英对照

新增于: v5.10.0 buffer | 要从中复制数据的现有 Buffer 或 Uint8Array。

将传入的 buffer 数据复制到新的 Buffer 实例上。

import { Buffer } from 'node:buffer'; const buf1 = Buffer.from('buffer'); const buf2 = Buffer.from(buf1); buf1[0] = 0x61; console.log(buf1.toString()); // 打印: auffer console.log(buf2.toString()); // 打印: bufferconst { Buffer } = require('node:buffer'); const buf1 = Buffer.from('buffer'); const buf2 = Buffer.from(buf1); buf1[0] = 0x61; console.log(buf1.toString()); // 打印: auffer console.log(buf2.toString()); // 打印: buffer

如果 buffer 不是 Buffer 或其他适用于 Buffer.from() 变体的类型，则将抛出 TypeError。

Buffer.from(object[, offsetOrEncoding[, length]])#

中英对照

新增于: v8.2.0 object 支持 Symbol.toPrimitive 或 valueOf() 的对象。 offsetOrEncoding | 字节偏移量或编码。 length 长度。

对于 valueOf() 函数返回的值不严格等于 object 的对象，则返回 Buffer.from(object.valueOf(), offsetOrEncoding, length)。

import { Buffer } from 'node:buffer'; const buf = Buffer.from(new String('this is a test')); // 打印: const { Buffer } = require('node:buffer'); const buf = Buffer.from(new String('this is a test')); // 打印:

对于支持 Symbol.toPrimitive 的对象，则返回 Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding)。

import { Buffer } from 'node:buffer'; class Foo { [Symbol.toPrimitive]() { return 'this is a test'; } } const buf = Buffer.from(new Foo(), 'utf8'); // 打印: const { Buffer } = require('node:buffer'); class Foo { [Symbol.toPrimitive]() { return 'this is a test'; } } const buf = Buffer.from(new Foo(), 'utf8'); // 打印:

如果 object 没有提到的方法或不是适合 Buffer.from() 变体的另一种类型，则将抛出 TypeError。

Buffer.from(string[, encoding])#

中英对照

新增于: v5.10.0 string 要编码的字符串。 encoding string 的编码。默认值: 'utf8'。

创建包含 string 的新 Buffer。 encoding 参数标识将 string 转换为字节时要使用的字符编码。

import { Buffer } from 'node:buffer'; const buf1 = Buffer.from('this is a tést'); const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex'); console.log(buf1.toString()); // 打印: this is a tést console.log(buf2.toString()); // 打印: this is a tést console.log(buf1.toString('latin1')); // 打印: this is a tÃ©stconst { Buffer } = require('node:buffer'); const buf1 = Buffer.from('this is a tést'); const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex'); console.log(buf1.toString()); // 打印: this is a tést console.log(buf2.toString()); // 打印: this is a tést console.log(buf1.toString('latin1')); // 打印: this is a tÃ©st

如果 string 不是字符串或其他适用于 Buffer.from() 变体的类型，则将抛出 TypeError。

Buffer.isBuffer(obj)#

中英对照

新增于: v0.1.101 obj 返回:

如果 obj 是 Buffer，则返回 true，否则返回 false。

import { Buffer } from 'node:buffer'; Buffer.isBuffer(Buffer.alloc(10)); // true Buffer.isBuffer(Buffer.from('foo')); // true Buffer.isBuffer('a string'); // false Buffer.isBuffer([]); // false Buffer.isBuffer(new Uint8Array(1024)); // falseconst { Buffer } = require('node:buffer'); Buffer.isBuffer(Buffer.alloc(10)); // true Buffer.isBuffer(Buffer.from('foo')); // true Buffer.isBuffer('a string'); // false Buffer.isBuffer([]); // false Buffer.isBuffer(new Uint8Array(1024)); // false Buffer.isEncoding(encoding)#

中英对照

新增于: v0.9.1 encoding 要检查的字符编码名称。返回:

如果 encoding 是支持的字符编码的名称，则返回 true，否则返回 false。

import { Buffer } from 'node:buffer'; console.log(Buffer.isEncoding('utf8')); // 打印: true console.log(Buffer.isEncoding('hex')); // 打印: true console.log(Buffer.isEncoding('utf/8')); // 打印: false console.log(Buffer.isEncoding('')); // 打印: falseconst { Buffer } = require('node:buffer'); console.log(Buffer.isEncoding('utf8')); // 打印: true console.log(Buffer.isEncoding('hex')); // 打印: true console.log(Buffer.isEncoding('utf/8')); // 打印: false console.log(Buffer.isEncoding('')); // 打印: false Buffer.poolSize#

中英对照

新增于: v0.11.3 默认值: 8192

这是用于池的预分配内部 Buffer 实例的大小（以字节为单位）。该值可以修改。

buf[index]#

中英对照

index

索引运算符 [index] 可用于获取和设置 buf 中位置 index 处的八位字节。这些值是指单个字节，因此合法值范围介于 0x00 和 0xFF（十六进制）或 0 和 255（十进制）之间。

该运算符继承自 Uint8Array，因此其越界访问行为与 Uint8Array 相同。换句话说，当 index 为负或大于等于 buf.length 时，buf[index] 返回 undefined，如果 index 为负或 >= buf.length，buf[index] = value 不修改缓冲区。

import { Buffer } from 'node:buffer'; // 每次一个字节地将 ASCII 字符串复制到 `Buffer` 中。 // （这仅适用于 ASCII-only 字符串。通常，应该使用 `Buffer.from()` 来执行此转换。） const str = 'Node.js'; const buf = Buffer.allocUnsafe(str.length); for (let i = 0; i < str.length; i++) { buf[i] = str.charCodeAt(i); } console.log(buf.toString('utf8')); // 打印: Node.jsconst { Buffer } = require('node:buffer'); // 每次一个字节地将 ASCII 字符串复制到 `Buffer` 中。 // （这仅适用于 ASCII-only 字符串。通常，应该使用 `Buffer.from()` 来执行此转换。） const str = 'Node.js'; const buf = Buffer.allocUnsafe(str.length); for (let i = 0; i < str.length; i++) { buf[i] = str.charCodeAt(i); } console.log(buf.toString('utf8')); // 打印: Node.js buf.buffer#

中英对照

创建此 Buffer 对象所基于的底层 ArrayBuffer 对象。

不保证此 ArrayBuffer 与原始 Buffer 完全对应。有关详细信息，请参阅 buf.byteOffset 上的说明。

import { Buffer } from 'node:buffer'; const arrayBuffer = new ArrayBuffer(16); const buffer = Buffer.from(arrayBuffer); console.log(buffer.buffer === arrayBuffer); // 打印: trueconst { Buffer } = require('node:buffer'); const arrayBuffer = new ArrayBuffer(16); const buffer = Buffer.from(arrayBuffer); console.log(buffer.buffer === arrayBuffer); // 打印: true buf.byteOffset#

中英对照

Buffer 底层 ArrayBuffer 对象的 byteOffset。

当在 Buffer.from(ArrayBuffer, byteOffset, length) 中设置 byteOffset 时，或者有时在分配小于 Buffer.poolSize 的 Buffer 时，缓冲区不会从底层 ArrayBuffer 上的零偏移量开始。

这在使用 buf.buffer 直接访问底层 ArrayBuffer 时可能会导致问题，因为 ArrayBuffer 的其他部分可能与 Buffer 对象本身无关。

创建与 Buffer 共享内存的 TypedArray 对象时的常见问题是，在这种情况下，需要正确指定 byteOffset：

import { Buffer } from 'node:buffer'; // 创建小于 `Buffer.poolSize` 的缓冲区。 const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // 当将 Node.js 缓冲区转换为 Int8Array 时， // 使用 byteOffset 仅引用包含 `nodeBuffer` 内存的 `nodeBuffer.buffer` 部分。 new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);const { Buffer } = require('node:buffer'); // 创建小于 `Buffer.poolSize` 的缓冲区。 const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // 当将 Node.js 缓冲区转换为 Int8Array 时， // 使用 byteOffset 仅引用包含 `nodeBuffer` 内存的 `nodeBuffer.buffer` 部分。 new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length); buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])#

中英对照

版本历史版本变更 v8.0.0

参数 target 现在可以是 Uint8Array。

v5.11.0

现在支持用于指定偏移量的额外参数。

v0.11.13

新增于: v0.11.13

target | 用于比较 buf 的 Buffer 或 Uint8Array。 targetStart target 内开始比较的偏移量。默认值: 0。 targetEnd target 中结束比较（不包括）的偏移量。默认值: target.length。 sourceStart buf 内开始比较的偏移量。默认值: 0。 sourceEnd buf 中结束比较（不包括）的偏移量。默认值: buf.length. 返回:

将 buf 与 target 进行比较并返回数字，该数字指示 buf 在排序顺序中是在 target 之前、之后还是与 target 相同。比较基于每个 Buffer 中的实际字节序列。

如果 target 与 buf 相同，则返回 0 如果排序时 target 应该在 buf 之前，则返回 1。如果排序时 target 应该在 buf 之后，则返回 -1。 import { Buffer } from 'node:buffer'; const buf1 = Buffer.from('ABC'); const buf2 = Buffer.from('BCD'); const buf3 = Buffer.from('ABCD'); console.log(buf1.compare(buf1)); // 打印: 0 console.log(buf1.compare(buf2)); // 打印: -1 console.log(buf1.compare(buf3)); // 打印: -1 console.log(buf2.compare(buf1)); // 打印: 1 console.log(buf2.compare(buf3)); // 打印: 1 console.log([buf1, buf2, buf3].sort(Buffer.compare)); // 打印: [ , , ] // （此结果相当于：[buf1, buf3, buf2]。）const { Buffer } = require('node:buffer'); const buf1 = Buffer.from('ABC'); const buf2 = Buffer.from('BCD'); const buf3 = Buffer.from('ABCD'); console.log(buf1.compare(buf1)); // 打印: 0 console.log(buf1.compare(buf2)); // 打印: -1 console.log(buf1.compare(buf3)); // 打印: -1 console.log(buf2.compare(buf1)); // 打印: 1 console.log(buf2.compare(buf3)); // 打印: 1 console.log([buf1, buf2, buf3].sort(Buffer.compare)); // 打印: [ , , ] // （此结果相当于：[buf1, buf3, buf2]。）

可选的 targetStart、targetEnd、sourceStart 和 sourceEnd 参数可用于分别将比较限制在 target 和 buf 内的特定范围内。

import { Buffer } from 'node:buffer'; const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]); const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]); console.log(buf1.compare(buf2, 5, 9, 0, 4)); // 打印: 0 console.log(buf1.compare(buf2, 0, 6, 4)); // 打印: -1 console.log(buf1.compare(buf2, 5, 6, 5)); // 打印: 1const { Buffer } = require('node:buffer'); const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]); const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]); console.log(buf1.compare(buf2, 5, 9, 0, 4)); // 打印: 0 console.log(buf1.compare(buf2, 0, 6, 4)); // 打印: -1 console.log(buf1.compare(buf2, 5, 6, 5)); // 打印: 1

如果 targetStart < 0、sourceStart < 0、targetEnd > target.byteLength 或 sourceEnd > source.byteLength，则抛出 ERR_OUT_OF_RANGE。

buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])#

中英对照

新增于: v0.1.90 target | 要复制到的 Buffer 或 Uint8Array。 targetStart target 内开始写入的偏移量。默认值: 0。 sourceStart buf 内开始复制的偏移量。默认值: 0。 sourceEnd buf 内停止复制的偏移量（不包括）。默认值: buf.length. 返回: 复制的字节数。

将数据从 buf 的区域复制到 target 的区域，即使 target 内存区域与 buf 重叠。

TypedArray.prototype.set() 执行相同的操作，可用于所有 TypedArray，包括 Node.js Buffer，尽管它采用不同的函数参数。

import { Buffer } from 'node:buffer'; // 创建两个 `Buffer` 实例。 const buf1 = Buffer.allocUnsafe(26); const buf2 = Buffer.allocUnsafe(26).fill('!'); for (let i = 0; i < 26; i++) { // 97 是 'a' 的十进制 ASCII 值。 buf1[i] = i + 97; } // 将 `buf1` 字节 16 到 19 复制到 `buf2` 中，从 `buf2` 的字节 8 开始。 buf1.copy(buf2, 8, 16, 20); // 这相当于： // buf2.set(buf1.subarray(16, 20), 8); console.log(buf2.toString('ascii', 0, 25)); // 打印: !!!!!!!!qrst!!!!!!!!!!!!!const { Buffer } = require('node:buffer'); // 创建两个 `Buffer` 实例。 const buf1 = Buffer.allocUnsafe(26); const buf2 = Buffer.allocUnsafe(26).fill('!'); for (let i = 0; i < 26; i++) { // 97 是 'a' 的十进制 ASCII 值。 buf1[i] = i + 97; } // 将 `buf1` 字节 16 到 19 复制到 `buf2` 中，从 `buf2` 的字节 8 开始。 buf1.copy(buf2, 8, 16, 20); // 这相当于： // buf2.set(buf1.subarray(16, 20), 8); console.log(buf2.toString('ascii', 0, 25)); // 打印: !!!!!!!!qrst!!!!!!!!!!!!! import { Buffer } from 'node:buffer'; // 创建 `Buffer` 并将数据从一个区域复制到同一 `Buffer` 内的重叠区域。 const buf = Buffer.allocUnsafe(26); for (let i = 0; i < 26; i++) { // 97 是 'a' 的十进制 ASCII 值。 buf[i] = i + 97; } buf.copy(buf, 0, 4, 10); console.log(buf.toString()); // 打印: efghijghijklmnopqrstuvwxyzconst { Buffer } = require('node:buffer'); // 创建 `Buffer` 并将数据从一个区域复制到同一 `Buffer` 内的重叠区域。 const buf = Buffer.allocUnsafe(26); for (let i = 0; i < 26; i++) { // 97 是 'a' 的十进制 ASCII 值。 buf[i] = i + 97; } buf.copy(buf, 0, 4, 10); console.log(buf.toString()); // 打印: efghijghijklmnopqrstuvwxyz buf.entries()#

中英对照

新增于: v1.1.0 返回:

从 buf 的内容创建并返回 [index, byte] 对的迭代器。

import { Buffer } from 'node:buffer'; // 记录 `Buffer` 的全部内容。 const buf = Buffer.from('buffer'); for (const pair of buf.entries()) { console.log(pair); } // 打印: // [0, 98] // [1, 117] // [2, 102] // [3, 102] // [4, 101] // [5, 114]const { Buffer } = require('node:buffer'); // 记录 `Buffer` 的全部内容。 const buf = Buffer.from('buffer'); for (const pair of buf.entries()) { console.log(pair); } // 打印: // [0, 98] // [1, 117] // [2, 102] // [3, 102] // [4, 101] // [5, 114] buf.equals(otherBuffer)#

中英对照

版本历史版本变更 v8.0.0

参数现在可以是 Uint8Array。

v0.11.13

新增于: v0.11.13

otherBuffer | 用于比较 buf 的 Buffer 或 Uint8Array。返回:

如果 buf 和 otherBuffer 具有完全相同的字节，则返回 true，否则返回 false。相当于 buf.compare(otherBuffer) === 0。

import { Buffer } from 'node:buffer'; const buf1 = Buffer.from('ABC'); const buf2 = Buffer.from('414243', 'hex'); const buf3 = Buffer.from('ABCD'); console.log(buf1.equals(buf2)); // 打印: true console.log(buf1.equals(buf3)); // 打印: falseconst { Buffer } = require('node:buffer'); const buf1 = Buffer.from('ABC'); const buf2 = Buffer.from('414243', 'hex'); const buf3 = Buffer.from('ABCD'); console.log(buf1.equals(buf2)); // 打印: true console.log(buf1.equals(buf3)); // 打印: false buf.fill(value[, offset[, end]][, encoding])#

中英对照

版本历史版本变更 v11.0.0

抛出 ERR_OUT_OF_RANGE 而不是 ERR_INDEX_OUT_OF_RANGE。

v10.0.0

负的 end 值会抛出 ERR_INDEX_OUT_OF_RANGE 错误。

v10.0.0

尝试使用零长度缓冲区填充非零长度缓冲区，则会触发抛出异常。

v10.0.0

为 value 指定无效字符串，则会触发抛出异常。

v5.7.0

现在支持 encoding 参数。

v0.5.0

新增于: v0.5.0

value | | | 用于填充 buf 的值。 offset 在开始填充 buf 之前要跳过的字节数。默认值: 0。 end 停止填充 buf（不包括在内）的位置。默认值: buf.length. encoding 如果 value 是字符串，则为 value 的编码。默认值: 'utf8'。返回: buf 的引用。

用指定的 value 填充 buf。如果没有给定 offset 和 end，则整个 buf 都会被填满：

import { Buffer } from 'node:buffer'; // 用 ASCII 字符 'h' 填充 `Buffer`。 const b = Buffer.allocUnsafe(50).fill('h'); console.log(b.toString()); // 打印: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhconst { Buffer } = require('node:buffer'); // 用 ASCII 字符 'h' 填充 `Buffer`。 const b = Buffer.allocUnsafe(50).fill('h'); console.log(b.toString()); // 打印: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

如果 value 不是字符串、Buffer 或整数，则将其强制为 uint32 值。如果结果整数大于 255（十进制），则 buf 将填充 value & 255。

如果 fill() 操作的最终写入落在多字节字符上，则仅写入适合 buf 的该字符的字节：

import { Buffer } from 'node:buffer'; // 用在 UTF-8 中占用两个字节的字符填充 `Buffer`。 console.log(Buffer.allocUnsafe(5).fill('\u0222')); // 打印: const { Buffer } = require('node:buffer'); // 用在 UTF-8 中占用两个字节的字符填充 `Buffer`。 console.log(Buffer.allocUnsafe(5).fill('\u0222')); // 打印:

如果 value 包含无效字符，则截断；如果没有有效的填充数据，则抛出异常：

import { Buffer } from 'node:buffer'; const buf = Buffer.allocUnsafe(5); console.log(buf.fill('a')); // 打印: console.log(buf.fill('aazz', 'hex')); // 打印: console.log(buf.fill('zz', 'hex')); // 抛出异常。const { Buffer } = require('node:buffer'); const buf = Buffer.allocUnsafe(5); console.log(buf.fill('a')); // 打印: console.log(buf.fill('aazz', 'hex')); // 打印: console.log(buf.fill('zz', 'hex')); // 抛出异常。 buf.includes(value[, byteOffset][, encoding])#

中英对照

新增于: v5.3.0 value | | | 要搜索的内容。 byteOffset 开始搜索 buf 的位置。如果为负数，则从 buf 的末尾开始计算偏移量。默认值: 0。 encoding 如果 value 是字符串，则这就是它的编码。默认值: 'utf8'。返回: 如果在 buf 中找到 value，则为 true，否则为 false。

相当于 buf.indexOf() !== -1。

import { Buffer } from 'node:buffer'; const buf = Buffer.from('this is a buffer'); console.log(buf.includes('this')); // 打印: true console.log(buf.includes('is')); // 打印: true console.log(buf.includes(Buffer.from('a buffer'))); // 打印: true console.log(buf.includes(97)); // 打印: true （97 是 'a' 的十进制 ASCII 值） console.log(buf.includes(Buffer.from('a buffer example'))); // 打印: false console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8))); // 打印: true console.log(buf.includes('this', 4)); // 打印: falseconst { Buffer } = require('node:buffer'); const buf = Buffer.from('this is a buffer'); console.log(buf.includes('this')); // 打印: true console.log(buf.includes('is')); // 打印: true console.log(buf.includes(Buffer.from('a buffer'))); // 打印: true console.log(buf.includes(97)); // 打印: true （97 是 'a' 的十进制 ASCII 值） console.log(buf.includes(Buffer.from('a buffer example'))); // 打印: false console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8))); // 打印: true console.log(buf.includes('this', 4)); // 打印: false buf.indexOf(value[, byteOffset][, encoding])#

中英对照

版本历史版本变更 v8.0.0

value 现在可以是 Uint8Array。

v5.7.0, v4.4.0

当传入 encoding 时，不再需要 byteOffset 参数。

v1.5.0

新增于: v1.5.0

value | | | 要搜索的内容。 byteOffset 开始搜索 buf 的位置。如果为负数，则从 buf 的末尾开始计算偏移量。默认值: 0。 encoding 如果 value 是字符串，则这是用于确定将在 buf 中搜索的字符串的二进制表示的编码。默认值: 'utf8'。返回: buf 中第一次出现 value 的索引，如果 buf 不包含 value，则为 -1。

如果 value 是：

字符串，value 根据 encoding 中的字符编码进行解释。 Buffer 或 Uint8Array, value 将全部使用。要比较部分 Buffer，则使用 buf.subarray。数字，value 将被解释为 0 和 255 之间的无符号 8 位整数值。 import { Buffer } from 'node:buffer'; const buf = Buffer.from('this is a buffer'); console.log(buf.indexOf('this')); // 打印: 0 console.log(buf.indexOf('is')); // 打印: 2 console.log(buf.indexOf(Buffer.from('a buffer'))); // 打印: 8 console.log(buf.indexOf(97)); // 打印: 8 （97 是 'a' 的十进制 ASCII 值） console.log(buf.indexOf(Buffer.from('a buffer example'))); // 打印: -1 console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8))); // 打印: 8 const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le'); console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le')); // 打印: 4 console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le')); // 打印: 6const { Buffer } = require('node:buffer'); const buf = Buffer.from('this is a buffer'); console.log(buf.indexOf('this')); // 打印: 0 console.log(buf.indexOf('is')); // 打印: 2 console.log(buf.indexOf(Buffer.from('a buffer'))); // 打印: 8 console.log(buf.indexOf(97)); // 打印: 8 （97 是 'a' 的十进制 ASCII 值） console.log(buf.indexOf(Buffer.from('a buffer example'))); // 打印: -1 console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8))); // 打印: 8 const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le'); console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le')); // 打印: 4 console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le')); // 打印: 6

如果 value 不是字符串、数字或 Buffer，则此方法将抛出 TypeError。如果 value 是数字，则它将被强制转换为有效的字节值（0 到 255 之间的整数）。

如果 byteOffset 不是数字，则会被强制为数字。如果强制转换的结果是 NaN 或 0，则将搜索整个缓冲区。此行为与 String.prototype.indexOf() 匹配。

import { Buffer } from 'node:buffer'; const b = Buffer.from('abcdef'); // 传入数字值，但不是有效字节。 // 打印: 2, 相当于搜索 99 或 'c'。 console.log(b.indexOf(99.9)); console.log(b.indexOf(256 + 99)); // 传入强制为 NaN 或 0 的 byteOffset。 // 打印: 1, 搜索整个缓冲区。 console.log(b.indexOf('b', undefined)); console.log(b.indexOf('b', {})); console.log(b.indexOf('b', null)); console.log(b.indexOf('b', []));const { Buffer } = require('node:buffer'); const b = Buffer.from('abcdef'); // 传入数字值，但不是有效字节。 // 打印: 2, 相当于搜索 99 或 'c'。 console.log(b.indexOf(99.9)); console.log(b.indexOf(256 + 99)); // 传入强制为 NaN 或 0 的 byteOffset。 // 打印: 1, 搜索整个缓冲区。 console.log(b.indexOf('b', undefined)); console.log(b.indexOf('b', {})); console.log(b.indexOf('b', null)); console.log(b.indexOf('b', []));

如果 value 为空字符串或空 Buffer 且 byteOffset 小于 buf.length，则返回 byteOffset。如果 value 为空且 byteOffset 至少为 buf.length，则返回 buf.length。

buf.keys()#

中英对照

新增于: v1.1.0 返回:

创建并返回 buf 个键（索引）的迭代器。

import { Buffer } from 'node:buffer'; const buf = Buffer.from('buffer'); for (const key of buf.keys()) { console.log(key); } // 打印: // 0 // 1 // 2 // 3 // 4 // 5const { Buffer } = require('node:buffer'); const buf = Buffer.from('buffer'); for (const key of buf.keys()) { console.log(key); } // 打印: // 0 // 1 // 2 // 3 // 4 // 5 buf.lastIndexOf(value[, byteOffset][, encoding])#

中英对照

版本历史版本变更 v8.0.0

value 现在可以是 Uint8Array。

v6.0.0

新增于: v6.0.0

value | | | 要搜索的内容。 byteOffset 开始搜索 buf 的位置。如果为负数，则从 buf 的末尾开始计算偏移量。默认值: buf.length - 1。 encoding 如果 value 是字符串，则这是用于确定将在 buf 中搜索的字符串的二进制表示的编码。默认值: 'utf8'。返回: buf 中最后一次出现 value 的索引，如果 buf 不包含 value，则为 -1。

与 buf.indexOf() 相同，除了找到最后一次出现的 value 而不是第一次出现。

import { Buffer } from 'node:buffer'; const buf = Buffer.from('this buffer is a buffer'); console.log(buf.lastIndexOf('this')); // 打印: 0 console.log(buf.lastIndexOf('buffer')); // 打印: 17 console.log(buf.lastIndexOf(Buffer.from('buffer'))); // 打印: 17 console.log(buf.lastIndexOf(97)); // 打印: 15 （97 是 'a' 的十进制 ASCII 值） console.log(buf.lastIndexOf(Buffer.from('yolo'))); // 打印: -1 console.log(buf.lastIndexOf('buffer', 5)); // 打印: 5 console.log(buf.lastIndexOf('buffer', 4)); // 打印: -1 const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le'); console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le')); // 打印: 6 console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le')); // 打印: 4const { Buffer } = require('node:buffer'); const buf = Buffer.from('this buffer is a buffer'); console.log(buf.lastIndexOf('this')); // 打印: 0 console.log(buf.lastIndexOf('buffer')); // 打印: 17 console.log(buf.lastIndexOf(Buffer.from('buffer'))); // 打印: 17 console.log(buf.lastIndexOf(97)); // 打印: 15 （97 是 'a' 的十进制 ASCII 值） console.log(buf.lastIndexOf(Buffer.from('yolo'))); // 打印: -1 console.log(buf.lastIndexOf('buffer', 5)); // 打印: 5 console.log(buf.lastIndexOf('buffer', 4)); // 打印: -1 const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le'); console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le')); // 打印: 6 console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le')); // 打印: 4

如果 value 不是字符串、数字或 Buffer，则此方法将抛出 TypeError。如果 value 是数字，则它将被强制转换为有效的字节值（0 到 255 之间的整数）。

如果 byteOffset 不是数字，则会被强制为数字。任何强制到 NaN 的参数，如 {} 或 undefined，都将搜索整个缓冲区。此行为与 String.prototype.lastIndexOf() 匹配。

import { Buffer } from 'node:buffer'; const b = Buffer.from('abcdef'); // 传入数字值，但不是有效字节。 // 打印: 2, 相当于搜索 99 或 'c'。 console.log(b.lastIndexOf(99.9)); console.log(b.lastIndexOf(256 + 99)); // 传入强制为 NaN 的 byteOffset。 // 打印: 1, 搜索整个缓冲区。 console.log(b.lastIndexOf('b', undefined)); console.log(b.lastIndexOf('b', {})); // 传递强制为 0 的 byteOffset。 // 打印: -1, 相当于传入 0。 console.log(b.lastIndexOf('b', null)); console.log(b.lastIndexOf('b', []));const { Buffer } = require('node:buffer'); const b = Buffer.from('abcdef'); // 传入数字值，但不是有效字节。 // 打印: 2, 相当于搜索 99 或 'c'。 console.log(b.lastIndexOf(99.9)); console.log(b.lastIndexOf(256 + 99)); // 传入强制为 NaN 的 byteOffset。 // 打印: 1, 搜索整个缓冲区。 console.log(b.lastIndexOf('b', undefined)); console.log(b.lastIndexOf('b', {})); // 传递强制为 0 的 byteOffset。 // 打印: -1, 相当于传入 0。 console.log(b.lastIndexOf('b', null)); console.log(b.lastIndexOf('b', []));

如果 value 为空字符串或空 Buffer，则返回 byteOffset。

buf.length#

中英对照

新增于: v0.1.90

返回 buf 中的字节数。

import { Buffer } from 'node:buffer'; // 创建 `Buffer` 并使用 UTF-8 向其写入一个较短的字符串。 const buf = Buffer.alloc(1234); console.log(buf.length); // 打印: 1234 buf.write('some string', 0, 'utf8'); console.log(buf.length); // 打印: 1234const { Buffer } = require('node:buffer'); // 创建 `Buffer` 并使用 UTF-8 向其写入一个较短的字符串。 const buf = Buffer.alloc(1234); console.log(buf.length); // 打印: 1234 buf.write('some string', 0, 'utf8'); console.log(buf.length); // 打印: 1234 buf.parent#

中英对照

弃用于: v8.0.0

稳定性: 0 - 弃用: 改为使用 buf.buffer 。

buf.parent 属性是 buf.buffer 的弃用别名。

buf.readBigInt64BE([offset])#

中英对照

新增于: v12.0.0, v10.20.0 offset 开始读取之前要跳过的字节数。必须满足：0

【本文地址】

buffer 缓冲区

buffer 缓冲区

今日新闻

推荐新闻